Homey Compose

Compose is a plugin integegrated in the Homey package. It allows for managing large apps more easily. This improves separation of concerns and keeps things organized. By default, the plugin is enabled when creating a new app with homey app create.

For example, when developing a driver you can create your driver manifest in the driver folder as driver.compose.json. A typical driver compose file can look like this:

com.athom.example/drivers/my_driver/driver.compose.json

"class": "socket",
"capabilities": [ "onoff", "dim" ],
"name": {
  "en": "My Driver",
  "nl": "Mijn Driver"
},
"images": {
  "large": "/drivers/my_driver/assets/images/large.png",
  "small": "/drivers/my_driver/assets/images/small.png"
}

This will only describe the relevant information for the current driver. When running compose, this information will be placed in the drivers property of app.json. If you have more than one driver, all the seperate driver.compose.json files from all drivers will be merged into the drivers property in app.json.

The basic principle of separating information is the same for all other entries that compose supports. Most of the compose files needs to be placed in the .homeycompose folder, located in the root folder of your Homey app.

Templating

Compose also allows for creating driver and setting templates to share common properties, for example RF signals, assets, etc. You can create a driver template by placing the shared properties in /.homeycompose/drivers/templates/<template_id>.json. Then extend from the template in your driver compose file by placing the template id the $extends property in driver.compose.json. Compose will copy all properties from the template to the final file. Should you want to overwrite an property, you can do so by placing it in your driver.compose.json.

com.athom.example/.homeycompose/drivers/templates/defaults.json

{
    "images": {
        "large": "{{driverAssetsPath}}/images/large.png",
        "small": "{{driverAssetsPath}}/images/small.png"
    },
    "icon": "{{driverAssetsPath}}/icon.svg",
    "capabilities": [],
    "class": "other"
}

com.athom.example/drivers/my_driver/driver.compose.json

{
    "name": {
      "en": "My Driver",
      "nl": "Mijn Driver"
},
    "$extends": [
        "defaults"
    ]
}

By using this template, you only have to place the values that are uniqiue to a driver in the driver.compose.json file. All other required properties are copied over from the template.

Compose file structure

The file structure when using compose looks as follows. These files are additionally to the files that an Homey app requires.

com.athom.example
├──  .homeycompose/
│    ├── app.json
│    ├── capabilities/
│    │     └── <id>.json
│    ├── screensavers/
│    │     └── <id>.json
│    ├── signals/
│    │     ├── 433/
│    │     │    └── <id>.json
│    │     ├── 868/
│    │     │    └── <id>.json
│    │     └── ir/
│    │         └── <id>.json
│    ├── flow/
│    │     ├── triggers/
│    │     │    └── <id>.json
│    │     ├── conditions/
│    │     │    └── <id>.json
│    │     └── actions/
│    │          └── <id>.json
│    ├── discovery/
│    │     └── <id>.json
│    ├── drivers/
│    │     ├── templates/
│    │     │    └── <template_id>.json
│    │     ├── settings/
│    │     │    └── <setting_id>.json
│    │     └── flow/
│    │         ├── triggers/
│    │         │    └── <id>.json
│    │         ├── conditions/
│    │         │    └── <id>.json
│    │         └── actions/
│    │              └── <id>.json
│    ├── locales/
│    │     ├── <locale>.json
│    │     └── <locale.foo>.json
└──  drivers/
     └── <driver_id>/
           ├── driver.compose.json
           ├── driver.flow.compose.json
           └── driver.settings.compose.json